<!DOCTYPE html>
<html>
<head>
<title>JSON-LD Primer</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<script type="text/javascript" src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>

<script type="text/javascript" class="remove">
      var respecConfig = {
          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
          specStatus:           "CG-DRAFT",
          //publishDate:          "2011-07-13",

          localBiblio: {
            "MICROFORMATS": {
              title: "Microformats",
              href: "https://microformats.org"
            },
            "JSON-LD-REQUIREMENTS": {
              title: "JSON-LD Requirements",
              href: "https://json-ld.org/requirements/latest/",
              authors: ["Gregg Kellogg"]
            }
          },

          // the specification's short name, as in https://www.w3.org/TR/short-name/
          shortName:            "json-ld-primer",
          subtitle:             "A Context-based JSON Serialization for Linked Data",
          // if you wish the publication date to be other than today, set this
          // publishDate:  "2009-08-06",

          // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
          // and its maturity status
          //previousPublishDate:  "2011-07-13",
          //previousMaturity:     "ED",
          //previousDiffURI:      "https://json-ld.org/requirements/ED/20110713/index.html",
          //diffTool:             "https://www.aptest.com/standards/htmldiff/htmldiff.pl",

          // if there a publicly available Editor's Draft, this is the link
          edDraftURI:           "https://json-ld.org/primer/latest/",
          includePermalinks:      true,
          noRecTrack:             true,

          // if this is a LCWD, uncomment and set the end of its review period
          // lcEnd: "2009-08-05",

          // editors, add as many as you like
          // only "name" is required
          editors:  [
              { name: "David I. Lehn", url: "http://dil.lehn.org/",
                company: "Digital Bazaar", companyURL: "https://digitalbazaar.com/" }
          ],

          github:    "https://github.com/json-ld/json-ld.org",

          // name of the WG
          wg:           "JSON for Linking Data W3C Community Group",

          // URI of the public WG page
          wgURI:        "https://www.w3.org/community/json-ld/",

          // name (with the @w3c.org) of the public mailing to which comments are due
          wgPublicList: "public-linked-json",

          // URI of the patent status for this WG, for Rec-track documents
          // !!!! IMPORTANT !!!!
          // This is important for Rec-track documents, do not copy a patent URI from a random
          // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
          // Team Contact.
          maxTocLevel: 3,
          //alternateFormats: [ {uri: "diff-20110507.html", label: "diff to previous version"} ],
      };
  </script>
  <style>
  .diff { font-weight:bold; color:#0a3; }
  </style>
</head>

<body>
<section id="abstract">

<p>This document attempts to provide a gentle introduction and examples of
<a href="/">JSON-LD</a> and to be a companion to the
<a href="/spec/latest/">JSON-LD specification</a>.</p>

</section>

<section id='sotd'>
<p>This document is an experimental work in progress.</p>
<div class="note">
This document is a very early attempt at a primer. It is very incomplete and should not be relied upon. Any comments and suggestions are welcome and can be sent to the <a href="https://json-ld.org/">JSON-LD</a> mailing list.
</div>
<!-- <p>
This document has been reviewed by W3C Members, by software
developers, and by other W3C groups and interested parties, and is
endorsed by the Director as a W3C Recommendation. It is a stable
document and may be used as reference material or cited from another
document. W3C's role in making the Recommendation is to draw attention
to the specification and to promote its widespread deployment. This
enhances the functionality and interoperability of the Web.
</p> -->
</section>

<section>
<h1>Introduction</h1>

<p>JSON-LD [[!JSON-LD]] combines the simplicity, power, and web ubiquity of
JSON [[!RFC4627]] with the concepts of Linked Data [[LINKED-DATA]]
[[JSON-LD-REQUIREMENTS]]. This document attempts to provide an introduction to
the concepts and usage of JSON-LD as well as some examples of how it can be
utilized in practice.</p>

<p>The requirements for JSON-LD can be found in [[JSON-LD-REQUIREMENTS]]
document and provide some basic definitions for concepts and terms used here.
The full specification for JSON-LD can be found in [[JSON-LD]] and is the basis
for the examples given here. Please refer to these documents as needed.</p>

<p>The semantic web and linked data are a foundation of knowledge
representation. What follows is a high-level view for the purposes of this
document. A full discussion of these concepts is out of the scope of this
document but see [[JSON-LD-REQUIREMENTS]] for a better description of these
concepts. Linked data systems are most often built using the concept of
&quot;triples&quot;. A single triple is built from a subject, a property, and a
value. A collection of these triples can form a graph of data.</p>

<p>Applications processing linked data can do so in a number of ways. One is to
access the raw triples. This is very flexible but often is cumbersome. Another
is to use some form of graph processing API, of which many variations exist.
Another is to create a tree view from a portion of the graph.</p>

<p>JSON-LD combines these features. At a low-level it provides a standardized
way to represent linked data in JSON. However, it has been found that much of
the linked data that is practically processed in JSON can be converted into tree
structures that are more natural to handle. Many programming languages even
offer native natural access to tree-like structures and no special APIs are
required.</p>

<p>Converting linked data graphs to easily accessible tree structures solves
one problem of linked data processing. Another is that in many cases the
components of a triple are represented as IRIs. Using long IRIs everywhere to
access data is very flexible and has many benefits but from a programming view
point is rather unwieldy.</p>

<p>JSON-LD provides the ability to add "context" to the data and "coerce"
values into forms that are easier to process. In fact, the end result of good
JSON-LD usage is data structures that look like simple JSON but are in fact
full linked data graphs. This provides a good deal of power for application
developers to convert the linked data they are processing into easily
manipulatable JSON data.</p>

<section>
<h2>Examples Theme</h2>

<p>Throughout this document the examples are based on a theme of processing
data for a online store. Linked data uses IRIs to represent types and
properties. The examples here will use two root URLs as well as a few simple
types and properties. A real linked data system should use a common standard
such as the
<a href="http://www.heppnetz.de/projects/goodrelations/">GoodRelations</a>
vocabulary.</p>

<dl>

<dt><code>http://ns.example.com/store#</code></dt>
<dd>The URL of the vocabulary. Abbreviated as <code>store</code> in CURIES.</dd>

<dt><code>http://store.example.com/</code></dt>
<dd>The fictitious &quot;Links Bike Shop&quot;. Abbreviated as <code>links</code> in CURIES.</dd>

<dt><code>store:Store</code></dt>
<dd>A store type. Instances have descriptive and product properties.</dd>

<dt><code>store:Product</code></dt>
<dd>A product for sale. Instances have descriptive, category, price, and availability properties.</dd>

<dt><code>store:Category</code></dt>
<dd>A product category type. Instances have descriptive properties.</dd>

<dt><code>store:product</code></dt>
<dd>A <code>store:Store</code> property linking to a <code>store:Product</code>.</dd>

<dt><code>store:category</code></dt>
<dd>A <code>store:Product</code> property linking to a <code>store:Category</code>.</dd>

<dt><code>store:price</code></dt>
<dd>A <code>store:Product</code> property linking to a price.</dd>

<dt><code>store:stock</code></dt>
<dd>A <code>store:Product</code> property linking to the quantity of the product in stock.</dd>

</dl>

</section>

<section>
<h2>Example: &quot;Links Bike Shop&quot;</h2>

<p class="note">FIXME: How should this be organized? Start with basic JSON, add LD? Start with pieces, combine into full doc? Something else?</p>

<p>Let's start by building up a fictitious bike store called &quot;Links Bike Shop&quot;.
We've already got our bike store setup at
<code>http://store.example.com/</code> and are using linked data principles.
Here's some of the URLs:</p>

<ul>
<li><code>http://store.example.com/</code>: The home page of the store.</li>
<li><code>http://store.example.com/products/links-swift-chain</code>: A chain product.</li>
<li><code>http://store.example.com/products/links-speedy-lube</code>: A chain lube product.</li>
</ul>

<p>We want to start creating some linked data for this fictitious store and
start with rough JSON data on the store itself.</p>

<pre id="p1" class="example highlight">
{
    "@id": "http://store.example.com/",
    "@type": "Store",
    "name": "Links Bike Shop",
    "description": "The most \"linked\" bike store on earth!"
}
</pre>

<p>That was easy, right? Next let's create some rough data for our two premier
products.</p>

<pre class="example highlight">
{
    "@id": "http://store.example.com/products/links-swift-chain",
    "@type": "Product",
    "name": "Links Swift Chain",
    "description": "A fine chain with many links.",
    "category": [
        "http://store.example.com/categories/parts",
        "http://store.example.com/categories/chains"
    ],
    "price": "10.00",
    "stock": 10
}
</pre>

<pre class="example highlight">
{
    "@id": "http://store.example.com/products/links-speedy-lube",
    "@type": "Product",
    "name": "Links Speedy Lube",
    "description": "Lubricant for your chain links.",
    "category": [
        "http://store.example.com/categories/lubes",
        "http://store.example.com/categories/chains"
    ],
    "price": "5.00",
    "stock": 20
}
</pre>

<p>To make this into a full JSON-LD document we combine the data, add a
<code>@context</code>, and adjust some values.</p>

<pre class="example highlight">
{
    "@id": "http://store.example.com/",
    "@type": "Store",
    "name": "Links Bike Shop",
    "description": "The most \"linked\" bike store on earth!",
    "product": [
        {
            "@id": "p:links-swift-chain",
            "@type": "Product",
            "name": "Links Swift Chain",
            "description": "A fine chain with many links.",
            "category": ["cat:parts", "cat:chains"],
            "price": "10.00",
            "stock": 10
        },
        {
            "@id": "p:links-speedy-lube",
            "@type": "Product",
            "name": "Links Speedy Lube",
            "description": "Lubricant for your chain links.",
            "category": ["cat:lube", "cat:chains"],
            "price": "5.00",
            "stock": 20
        }
    ],
    "@context": {
        "Store": "http://ns.example.com/store#Store",
        "Product": "http://ns.example.com/store#Product",
        "product": "http://ns.example.com/store#product",
        "category":
        {
          "@id": "http://ns.example.com/store#category",
          "@type": "@id"
        },
        "price": "http://ns.example.com/store#price",
        "stock": "http://ns.example.com/store#stock",
        "name": "http://purl.org/dc/terms/title",
        "description": "http://purl.org/dc/terms/description",
        "p": "http://store.example.com/products/",
        "cat": "http://store.example.com/category/"
    }
}
</pre>

</section>

</section>

<section>
<h1>Use Cases</h1>

<p>The following use cases are motivating in the design of JSON-LD.</p>

<section>
<h2>Linked Data Processing</h2>

<p>JSON-LD provides the ability to take linked data from many different sources
and present it to an application in an easy to process JSON format. In many
cases the transformation from a linked data graph to a JSON tree makes the data
appear to just be a simple JSON structure.</p>

</section>

<section>
<h2>Conversion to Known Format</h2>

<p>Linked data may be input in a form that an application is not prepared to
handle. JSON-LD offers the ability to convert linked data into a form that each
application can specify on its own.</p>

</section>

</section>

<section>
<h1>Data Sources</h1>

<p>JSON-LD is not dependent on any particular source of data. It is possible to
convert many types of semantic web formats into JSON-LD. This is one of the
classic benefits of the semantic web and its foundation of triples. Depending
on the application and where it is used, a source of data may come from many
places:</p>

<ul>
<li>JSON-LD (native data) [[JSON-LD]]</li>
<li>RDFa [[RDFA-CORE]]</li>
<li>Microdata [[MICRODATA]]</li>
<li>Microformats [[MICROFORMATS]]</li>
<li>RDF</li>
<li>various other triples formats (N-Triples, Turtle, etc)</li>
</ul>

<p>A source-specific processor must convert the data into JSON-LD. In most
cases if you can convert a data format into a form of triples, then the
conversion into an expanded form of JSON-LD is trivial. Once this has taken
place, it is possible to use framing and other JSON-LD processing concepts to
convert the data into a form which is easier to process at the application
level. This ability allows you process linked data provided in many formats in
a standardized way.</p>

<section>
<h2>Example: Linked Data Format Independence</h2>

<p>FIXME: same triples in JSON-LD, RDFa, Microdata, triples</p>

</section>
</section>

<section>
<h1>Framing</h1>

<p>Many applications wish to access data as if it is a simple tree structure.
This is natural in many programming languages and often comes for free without
a specialized API. The flexibility of the JSON-LD format and linked data it
represents does come with a problem.</p>

<section>
<h2>Example: Basic Framing</h2>

<p>FIXME: ex of simple frame features</p>

</section>

<section>
<h2>Example: Alternate Views</h2>

<p>FIXME: multiple ex of different views into the same source data</p>

</section>
</section>

<section>
<h1>Putting It All Together</h1>

<section>
<h2>Example: ?</h2>

<p>FIXME: more complex example</p>

</section>
</section>

</body>
</html>
